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Executive  Branch,  the  Congress  and/or  the  public,  or  (c)  address  Inues  that  have 
significant  economic  implications.  IDA  Reports  ere  reviawed  by  outside  panels  of  experts 
to  ensure  tbeir  high  quality  and  relevance  to  the  problems  studied,  and  they  are  released 
by  the  President  of  IDA. 

Group  Reports 

Group  Reports  record  the  findings  and  results  ol  IDA  established  working  groups  and 
panels  composed  ol  senior  individuals  addressing  major  issues  which  otherwise  would  be 
the  subject  of  an  IDA  Report.  IDA  Group  Reports  are  reviewed  by  the  senior  Individuals 
responsible  for  the  project  nod  others  as  selected  hy  IDA  to  ensure  tbeir  high  quality  and 
relevance  to  the  problems  studied,  and  are  released  by  the  President  of  IDA. 

Papers 

Papers,  also  authoritative  and  carefully  considered  products  of  IDA,  address  studies  that 
are  oarrower  in  scopn  than  those  covered  In  Reports.  IDA  Papers  are  reviewed  to  ensure 
that  they  meet  the  high  standards  expected  of  refereed  papers  in  professional  journals  or 
formal  Agency  reports. 

Documente 

IDA  Documents  are  used  lor  the  convenience  ol  the  sponsors  or  the  analysis  (a)  to  record 
substantive  work  done  in  quick  reaction  studies,  (b)  to  record  the  proceedings  of 
conferences  and  meetings,  (c)  to  make  available  preliminary  and  tentative  results  ol 
analyses,  (d)  to  record  data  developed  In  the  course  of  an  investigation,  or  (e)  to  forward 
information  that  Is  ossentlally  unanalyzed  and  unevaluated.  The  review  ol  IDA  Documents 
is  suited  to  their  content  and  intended  use. 
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PREFACE 


This  paper  communicates  the  results  of  a  study  the  Institute  for  Def^  .  .  Analyses 
(IDA)  conducted  of  relevant  standards  that  will  impact  the  preparation  and  delivery  of 
software  documentation  prepared  by  the  Software  Technology  for  Adaptable,  Reliable 
Systems  (STARS)  contractors.  This  document  responds  to  the  objective  of  Task  Order  T- 
D5-429,  Software  Technology  Acceleration  Project,  which  is  "to  provide  technical 
expertise  and  support  in  development  of  strategies  designed  to  insert  modem  software 
practices  throughout  the  DoD  community.”  This  study  will  be  used  to  develop  the 
standards  for  STARS  software  documentation  and  will  be  used  by  the  STARS  Office  to 
provide  guidance  to  their  Prime  Contractors  and  their  sub-contractors. 

The  document  was  reviewed  by  the  following  members  of  IDA:  Dr.  David  Camey, 
Mr.  Qyde  Roby,  and  Dr.  John  Salasin. 
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1.0  INTRODUCTION 
1.1  PURPOSE 

This  paper  provides  a  summary  of  seven  standards  that  may  impact  Software 
Technology  for  Adaptable,  Reliable  Systems  (STARS)  software  documentation  and  the  use 
of  the  Standard  Generalized  Markup  Language  (SGML).  The  analysis  of  these  standards  is 
based  on  the  following  steps  which  should  be  taken  when  a  program,  such  as  STARS, 
plans  to  use  SGML  for  the  electronic  transfer  of  its  software  documentation. 

•  Establish  types  of  required  documentation. 

•  Establish  document  style  and  structure  guidelines. 

•  Establish  document  formatting  guidelines. 

•  Establish  a  standard  for  graphical  data. 

•  Establish  appropriate  document  type  definitions. 

There  are  several  standards  that  address  the  preparation  and  presentation  of 
documents.  This  list  was  not  meant  to  be  inclusive.  However,  this  list  represents  those 
standards  that  were  felt  to  have  the  most  impact  on  the  STARS  decision  to  use  SGML. 

•  DoD-STD-7935,  "Automated  Data  Systems  (ADS)  Documentation,"  15 
Februaty  1983. 

•  MIL-M-38784B,  "Manuals,  Technical:  General  Style  and  Format 
Requirements,"  16  April  1983. 

•  ISO-8879- 1986(E),  "Information  Processing  -  Text  and  Office  Systems 
-  Standard  Generalized  Markup  Language  (SGML),"  15  October  1986. 

•  MEL-STD- 1 840A,  "Automated  Interchange  of  Technical  Information," 

22  December  1987. 

•  MIL-D-28000,  "Digital  Representation  for  Communication  of  Product 
Data:  IGES  Application  Subsets,"  22  December  1987. 

•  MIL-M'28()01 ,  "Markup  Requirements  and  Generic  S^le  Specification 
for  Electronic  Printed  Ou^ut  and  Exchange  of  Text,”  26  January  1988. 

•  DoD-STD-2167A,  "Defense  System  Software  Development,"  29 
February  1988. 

The  STARS  Program  has  already  announced  its  intention  to  use  SGML.  Now  the 
STARS  Program  must  make  a  decision  about  the  standards  it  will  adopt  when  using 
SGML.  ISO-8879  only  provides  guidance  for  using  SGML  document  types,  inclusion  of 
graphics,  and  even  the  SGML-related  tags  are  decisions  that  are  left  to  the  user.  Other 
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standards  must  be  used  in  conjunction  with  ISO-8879  to  meet  the  user's  needs.  Document 
format,  structure  and  style  must  be  standardized  within  the  Program  to  ensure  consistency 
in  both  the  preparation  and  delivery  of  software  documentation  by  pime  contractors. 

1.2  BACKGROUND 

The  STARS  Program  will  result  in  the  development  and  demonstration  of  a 
software  development  and  maintenance  technology  which  will  improve  the  quality  and 
reduces  the  cost  of  Department  of  Defense  (DoD)  software.  Appropriate  documentation 
will  need  to  be  developed  along  with  the  software.  The  STARS  Program  Office  has 
decided  to  use  SGML  in  the  preparation  and  electronic  transfer  of  this  documentation. 

During  the  review  of  the  proposals  presented  by  the  STARS  prime  contractors,  it 
became  obvious  that  (1)  there  were  several  standards  related  to  the  preparation  and 
distribution  of  software  documentation  and  (2)  that  not  all  the  primes  were  using  or  were 
aware  of  the  same  standards.  This  paper  was  prepared  to  familiarize  IDA,  the  sponsor,  and 
the  prime  contractors  with  these  standards  and  how  the  standards  may  impact  the  STARS 
Program  Manager's  decision  to  use  SGML.  This  document  assumes  that  the  reader  is 
familiar  with  SGML  and  its  concepts.  If  the  reader  is  not  familiar  with  SGML,  suggested 
reading  includes  Appendix  A  of  ISO-8879  and  the  article  by  Coombs,  Renear,  and  DeRose 
in  the  November  1987  issue  of  Communications  of  the  ACM  entitled  "Markup  Systems 
and  the  Future  of  Scholarly  Text  Processing." 

1.3  SCOPE 

Section  2.0  of  this  paper  provides  a  short  summary  of  the  seven  relevant  standards. 
Section  3.0  discusses  how  the  standards  may  impact  each  other  and  the  STARS  program. 
Section  4.0  is  a  list  of  recommended  actions  STARS  should  take  to  establish  a  conunon 
SGML  standard  for  the  competing  prime  contacts. 

1.4  REFERENCES 
Government 

Department  of  Defense,  DoD-STD-7935,  "Automated  Data  Systems  (ADS) 
Documentation,"  15  February  1983. 

Department  of  Defense,  MIL-M-38784B,  "Manuals,  Technical:  General  Style  and 
Format  Requirements,"  16  April  1983. 

Department  of  Defense,  MIL-STD-1840A,  "Automated  Interchange  of  Technical 
Information,"  22  December  1987. 

Department  of  Defense,  MIL-D-28000,  "Digital  Representation  for  Communication 
of  Product  Data:  IGES  Application  Subsets,"  22  December  1987. 


► 


) 


» 


Department  of  Defense,  MIL-M-28001,  "Markup  Requirements  and  Generic  Style 
Specification  for  Electronic  Printed  Output  and  Exchange  of  Text,"  26  January 
1988. 

Department  of  Defense,  DoD-STD-2167A,  "Defense  System  Software 
Development,”  29  February  1988. 

Department  of  Defense,  US  Government  Printing  Office,  Style  Manual,  1984. 

Department  of  Defense,  DoD-D-1000,  "Engineering  Drawings  and  Associated  Lists," 
Revision  B,  Amendment  4, 18  August  1987. 

Non-Government 

American  National  Standards  Institute,  "Digital  Representation  for  Communication  of 
Product  Definition  Data,"  ANSI  Y14.26M,  1981.  (Note:  This  is  the  same  as  IGES  V3.0 
specification.) 

Coombs,  Jean  H.,  Allen  H.  Renear,  and  Steven  J.  DeRose,  "Markup  Systems  and  the 
Future  of  Scholarly  Text  Processing,"  Communications  of  the  ACM,  Volume  30,  Number 
11,  November  1987,  pp,  933-947. 

International  Organization  of  Standards,  ISO-8879- 1986(E),  "Information 
Processing  -  Text  and  Office  Systems  -  Standard  Generalized  Markup  Language 
(SGML),"  15  October  1986,  UDC  Number  681.3.06.  (Available  through  the 
American  National  Standards  Institute.) 

Smith,  Joan  M.  and  Robert  Stutely,  SGML:  The  User's  Guide  to  ISO  8879,  Ellis 
Horwood  Limited,  1988. 


1.5  TERMS  AND  ABBREVIATIONS 
ADS  Automated  Data  Systems 

ANSI  American  National  Standards  Institute 

ASCn  American  Standard  Code  for  Information  Exchange 

CAD  Computer-Aided  Design 

CALS  Computer-aided  Acquisition  and  Logistics  Su^^rt 

CGM  Computer  Graphics  Metafile 

DID  Data  Item  Descriptions 

EtoD  Department  of  Defense 

DoD-D  Department  of  Defense  Directive 

DoD-STD  Department  of  Defense  Standard 
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UTD 

Document  Type  Definition 

IDA 

Institute  for  Defense  Analyses 

IGES 

Initial  Graphics  Exchange  Specification 

ISO 

International  Organization  of  Standards 

MIL-D 

Military  Document 

MIL-HDBK 

Military  Handbook 

MILrM 

Military  Specification 

MH^STD 

Military  Standard 

PDL 

Page  Description  Language 

SGML 

Standard  Generalized  Markup  Language 

STARS 

Software  Technology  for  Adaptable,  Reliable,  Systems 

UDC 

Universal  Decimal  Classification 
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2.0  STANDARDS 

2  1  OVERVffiW 

Three  of  the  standards  reviewed,  MIL-M-28000,  MIL'M-28001  and  MIL-STD- 
1840A,  were  developed  by  the  Computer-aided  Acquisition  and  Logistics  Support  (CALS) 
Policy  Office.^ 

ISO-8879  is  the  official  SGML  standard  adopted  by  DoD  and  provides  the  syntax 
for  describing  a  document  Both  ISO-8879  and  MIL-M-28001  provide  Document  Type 
Descriptions  (DTDs)  that  may  serve  as  guidelines  to  developing  the  STARS  DTDs.  DoD 
standards  2 167 A  and  7935  discuss  the  types  of  documents  that  are  required  in  the 
development  of  software  for  weapon  systems  and  automated  data  systems.  These  two 
standards,  along  with  MIL-M-38784B,  also  establish  guidelines  for  document  style  and 
structure.  MIL-M-3878A  and  MIL-STD-1840A  address  the  formatting  issues  for  technical 
manuals.  MIL-STD-184QA  and  MIL-M-28000  discuss  the  structure  and  format  of 
graphical  data  and  its  inclusion  in  various  types  of  publications. 

2.2  DOD.STD.7935,  ’’AUTOMATED  DATA  SYSTEMS  (ADS) 

DOCUMENTATION,”  15  FEBRUARY  1983 

DoD-STD-7935  provides  guidelines  for  the  development  and  revision  of  the 
documentation  for  Automated  Data  Systems  (ADS)  of  applications  computer  programs,  and 
prescribes  the  standards  and  descriptions  for  each  of  the  technical  documents  to  be 
produced  during  the  life  cycle  of  an  ADS.  ADS  is  defined  as  "an  assembly  of  procedures, 
processes,  methods,  routines,  or  techniques  (including,  but  not  limited  to,  computer 
programs)  united  by  some  form  of  regulated  interaction  to  form  an  organized  whole, 
specifically  designed  to  make  use  of  automatic  data  processing  equipment"  The  objective 
of  the  standard  is  to  provide  managers  of  ADS  projects  with  documentation  of  uniform 
format  and  content  for  review  to  assure  the  meeting  of  significant  development  milestones. 
It  also  provides  ADS  technicians  widi  a  standard  record  of  technical  information  as  a  basis 
for  coordination  of  later  ADS  development  or  use  modffication.  There  are  eleven  technical 
documents  described  in  the  standard;  Functional  Description,  System/Subsystem 
Specffication,  Data  Base  Specification,  Computer  Operational  Manual,  Test  Plan, 
Implementation  Procedures,  Data  Requirements  Document,  Program  Specification,  Users 


^In  August  1988,  Dqwty  Defense  SecreUfy  William  H.  Taft  oidered  DoD  weiqxxis  programs  to  use  the 
dau  interohange  standards  developed  by  CALS.  Beades  the  three  standards  mentioned  above,  the  CALS 
Support  Office  has  three  draft  standards  out  for  review:  MIL-R-Raster,  "Raster  Grqihics;"  MD^D-CCM, 
"COM  Application;"  andMIL-HDBK-XXX,  "CALS  Implemenudon  Guide." 
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Manual,  Program  Maintenance  Manual,  and  Test  Analysis  Report  A  proposed  outline  and 
text  format  for  each  document  type  is  provided  in  Section  3.0  of  the  standard. 

2.3  MIL-M-38784B,  "MANUALS,  TECHNICAL:  GENERAL  STYLE 
AND  FORMAT  REQUIREMENTS,"  16  APRIL  1983 
MIL-M-38784B  is  a  military  specification  approved  by  the  DoD  for  use  in 

developing  technical  manuals.  Technical  manuals  are  publications  that  contain  instructions 
for  the  installation,  operation,  maintenance,  training,  and  support  of  weapon  systems, 
weapon  system  components  and  support  equipment  Manuals  prepared  in  accordance  with 
this  specification  are  intended  for  use  in  the  operation  and  maintenance  of  equipment  or  for 
accomplishment  of  assigned  missions.  It  covers  the  general  style  and  format  requirements 
for  the  preparation  of  manuscripts  and  reproducible  copy  for  standard  technical  manuals 
and  changes  to  those  manuals.  The  only  decision  left  to  the  author  of  a  technical  manual  is 
the  actual  technical  content  of  the  manual;  even  the  style  of  writing  is  specified  {U.S. 
Government  Priming  Office  Style  Manual). 

The  major  section  of  the  document.  Section  3.2,  is  dedicated  to  format  issues.  The 
specification  covers  everything  from  the  size  of  the  paper  to  capitalization  to  suggested  type 
styles  and  sizes. 

The  specification  identifies  the  structure  of  a  technical  manual.  It  specifies  what 
will  be  included  in  the  manual  outline  and  publication  divisions  (volumes,  parts,  chapters, 
section  and  paragraphs).  Paragraphs  are  divided  into  primary  and  subordinate  paragraphs. 

The  last  sections  of  the  specification  discuss  how  to  make  changes  to  a  technical 
manual,  quality  assurance  provisions  (readability,  etc.)  and  preparation  for  delivery 
(packaging). 

2.4  ISO-8879- 1986(E),  "INFORMATION  PROCESSING  -  TEXT  AND 
OFFICE  SYSTEMS  -  STANDARD  GENERALIZED  MARKUP 
LANGUAGE  (SGML),"  15  OCTOBER  1986 

The  ISO-8879  standard  was  adopted  for  use  by  the  DoD  on  4  January  1988. 
SGML  standardizes  the  application  of  generic  coding  and  generalized  markup  concepts.  It 
provides  a  coherent  and  unambiguous  syntax  for  describing  whatever  a  user  chooses  to 
identify  within  a  document  The  language  includes: 

•  an  abstract  syntax  for  descriptive  markup  of  document  elements 

•  a  reference  concrete  syntax  that  binds  the  abstract  syntax  to  particular 
delimiter  characters  and  quantities 
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•  markup  declarations  that  allow  the  user  to  define  a  specific  vocabulary 
of  generic  identifiers  and  attributes  for  difference  document  types 

•  provision  for  arbitrary  data  content 

•  entity  references 

•  special  delimiters  for  processing  instructions  to  distinguish  them  from 
descriptive  markup 

SGML  was  developed  to  solve  such  problems  as  device  and  system  dependency, 
difficulties  in  integrating  new  technologies  in  the  publications  field,  rekeying  of  data  for 
multiple  purposes,  keying  complexities,  inability  to  develop  multi-purpose  training 
programs  and  the  inability  to  interchange  the  structure  of  the  text  The  whole  idea  behind 
generic  markup  is  to  use  nouns  and  adjectives  to  describe  parts  of  a  document — to  identify 
what  something  is,  not  how  it  looks.  SGML  is  a  language  to  represent  user-defined 
document  structures  in  a  rigorous  and  formal  manner  so  that  a  computer  may  process  it 

SGML  can  be  used  to  describe  any  type  of  textual  data  from  a  novel  to  a 
mathematical  equation.  The  Document  Type  DeHnition  (DTD),  however,  narrows  the 
metalanguage  for  use  with  a  speciHc  application.  A  DTD  is  a  concise  statement  of  what 
elements,  entities,  and/or  attributes  are  allowed  in  a  particular  document.  Through  the 
DTD,  an  application  can  rigorously  and  strictly  define  a  class  of  documents  such  as  a  job 
guide  or  flight  manual.  Descriptive  tags  may  be  tailored  to  the  application  with  no  concern 
for  the  delivery  method  or  output  device. 

2.5  MIL.STD-1840A,  "AUTOMATED  INTERCHANGE  OF  TECHNICAL 

INFORMATION,"  22  DECEMBER  1987 

The  purpose  of  this  publication  is  to  standardize  the  digital  interface  between 
organizations  or  systems  exchanging  digital  forms  of  technical  information  necessary  for 
the  logistic  support  of  weapon  systems  throughout  their  life  cycle.  This  standard  addresses 
technical  information  and  product  definition  data.  It  standardizes  the  format  and 
information  structures  of  digital  data  files  used  for  the  transfer  and  archival  storage  of 
digital  technical  information.  The  format,  information  structures,  and  transfer  procedures 
are  applicable  in  all  cases  where  the  information  can  be  prepared  and  received  in  the  f<»m  of 
American  Standard  Code  for  Information  Exchange  (ASCII)  text  files,  product  definition 
data  files,  raster  image  files  or  graphics  files. 

Technical  publications  consist  of  text  and  associated  illustrations.  The  files  of  a 
technical  publication  consist  of  a  declaration  file,  text  Hies  (in  ASCTI)  tagged  to  the  contract 
(may  use  MIL-M-28001),  illustration  files  (in  Initial  Graphics  Exchange  Specification 
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(IGES),  Computer  Graphics  Metafile  (CGM)  or  raster  format),  files  in  Page  Description 
Language  (PDL)  form  and  other  files  (output  specification  file,  special  word  file,  etc.)- 
The  standard  dictates  very  detailed  requirements  for  the  structure,  content  and  order  of 
information.  For  example,  the  declaration  file  must  precede  the  data  files  and  provide 
information  about  the  identifications,  source,  destination,  classification,  etc.  of  the 
document  The  standard  also  specifies  the  file  header  records  for 
textual  data  CGM  data 

document  type  definition  PDL 

IGES  data  gray  scale 

raster  d^ta  special  word 

ouqiut  specification  data 

2.6  MIL-D-28000,  "DIGITAL  REPRESENTATION  FOR  COMMUNI¬ 

CATION  OF  PRODUCT  DATA:  IGES  APPLICATION  SUBSETS  " 
22  DECEMBER  1987 

This  specification  identifies  the  requirements  to  be  met  when  product  definition  data 
is  delivered  in  the  digital  format  of  IGES  as  specified  by  ANSI  standard,  Y14.26M  - 
Digital  Representation  for  Communication  of  Product  Definition  Data.  MIL-D-28()00  is 
designed  to  be  incorporated  into  a  contract  to  define  the  technical  requirements  to  be  met 
when  purchasing  product  definition  data  or  product  data  in  digital  form.  Produa  definition 
data  is  defined  as  "the  totality  of  data  elements  required  to  completely  define  a  product. 
Product  definition  data  includes  geometry,  topology,  relationship,  tolerances,  attributes  and 
features  necessary  to  completely  define  a  component  part  or  an  assembly  of  parts  for  the 
purpose  of  design,  analysis,  manufacture,  test,  and  inspection."  The  specification  defines 
product  data  as  "all  data  elements  necessary  to  define  the  geometry,  the  function,  and  the 
behavior  of  a  piece  part  or  an  assembly  of  parts  over  its  entire  lifespan."  IGES  is  a 
specification  that  provides  a  neutral  format  for  the  representation  and  transfer  of  vector 
graphics  data  used  for  illustration  purposes  among  Computer-Aided  Design  (CAD)  systems 
and  application  programs.^ 

This  specification  defines  the  technical  requirements  for  the  exchange  of  digital 
product  data  in  specific  application  subsets.  These  subsets  are  technical  illustrations, 
engineering  drawings,  and  electrical/electronic  applications.  The  technical  illustration 
subset  addresses  entities  that  support  the  exchange  of  figures  and  illustrations  normally 

^These  definitions  can  be  found  in  section  6.6  of  MIL'D-28000,  pages  31-33. 
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found  in  a  technical  publication.  The  emphasis  is  on  visual  clarity  for  human  interpretation. 
The  engineering  drawings  subset  is  used  to  encode  product  data  being  acquired  in 
accordance  with  DoD-D-1000  (Engineering  Drawings  and  Associate  Lists)  for  delivery  in 
digital  form.  Exchange  emphasis  is  on  completeness,  visual  equivalency  for  human 
interpretation,  and  functionality  of  the  received  drawing  model.  The  electrical/electronic 
applications  subset  addresses  the  representation  and  exchange  of  electrical  and  electronic 
products  including  printed  wiring  boards,  printed  wiring  assemblies,  hybrid 
microassemblies,  cables,  and  wiring  harnesses.  Emphasis  is  on  component  and  circuit 
element  descriptions,  their  placement,  their  cormectivity,  and  the  routing  of  electrical  paths. 
2.7  MIL-M-28001,  "MARKUP  REQUIREMENTS  AND  GENERIC 

STYLE  SPECIFICATION  FOR  ELECTRONIC  PRINTED  OUTPUT 

AND  EXCHANGE  OF  TEXT,"  26  JANUARY  1988 

This  specification  establishes  the  requirements  for  the  digital  data  form  of  technical 
publications.  Data  prepared  in  conformance  to  these  requirements  will  facilitate  the 
automated  preparation,  storage,  retrieval,  exchange,  and  processing  of  technical  documents 
from  heterogeneous  data  sources.  The  requirements  set  forth  by  this  specification  include: 

*  procedures  and  symbology  for  markup  of  unformatted  text  in 
accordance  with  this  specific  application  of  SGML 

*  SGML  compatible  codes  that  will  conform  a  technical  publication  to 
specific  format  requirements 

*  output  control  codes  that  will  conform  automated  document  processing 
functions  to  a  uniform  structure 

This  specification  establishes  the  requirements  for  the  digital  forms  of  all  technical 
publications.  Data  files  satisfying  the  requirements  of  this  specification  will  be  one  of  two 
types:  Type  I  -  MIL-M-38784A  conforming  technical  manuals  and  Type  II  -  technical 
manuals  conforming  to  other  military  specifications.  Documents  prepared  in  accordance 
with  38784  and  28001  must  conform  to  the  DTD  defined  in  Appendix  A  and  the  output 
specification  in  Appendix  C  of  28001.  The  DTD  and  output  specification  for  a  MIL-M- 
38784A  conforming  manual  do  not  have  to  be  delivered  with  the  tagged  text.  Technical 
manuals  conforming  to  other  military  specifications  may  develop  their  own  DTD  but  must 
use  only  those  tags  in  the  baseline  tag  set  defined  in  Appendix  B  of  28001.  In  this  case, 
the  DTD  must  be  delivered  with  the  publication  along  with  a  compatible  output 
specification. 


9 


This  specification  addresses  the  five  steps  in  the  publication  preparation  process: 

•  Creating  a  DTD  for  publication  control; 

•  Authoring  the  publication  and  inserting  SGML  markup  tags; 

•  Verifying  the  syntax  according  to  the  rules  of  SGML; 

•  Using  the  output  specification  to  compose  the  document  so  that 
produced  copy  corresponds  to  the  proper  formal  and  style;  and 

•  Generating  a  text  presentation  metafile  in  PDL  to  drive  the  display 
device. 

The  heart  of  this  specification  is  found  in  the  appendices.  Appendix  A  specifies  the 
role  played  by  the  DTD  in  an  SGML  implementation;  a  general  description  of  DTD 
structure  and  content;  the  specific  DTDs  available  for  use  in  authoring,  validating,  and 
verifying  an  SGML-tagged  technical  document;  and  procedures  for  DTD  development 
The  appendix  introduction  provides  an  overview  of  the  concepts  behind  the  SGML 
standard,  a  brief  tutorial  on  reading  an  SGML  DTD,  guidelines  for  using  SGML  tags  and 
DoD's  SGML  declaration.  Two  DTDs  are  also  presented  in  Appendix  A.  This  first  DTD 
is  for  use  when  preparing  a  document  that  conforms  with  MIL-M-38784A.  The  second 
uses  the  same  elements  as  the  first  DTD  with  the  addition  of  more  subordinate  paragraphs 
and  steps.  This  DTD  may  be  used  for  MIL-M-38784A  non-conforming  documents  or  as  a 
model  for  the  development  of  a  more  appropriate  DTD.  Both  DTDs  allow  for  four  types  of 
non-SGML  data:  IGES  data,  CGM  data,  CCITT  Group  4  data,  and  system  generated  data. 

Appendix  B  contains  an  alphabetical  listing  of  all  elements  contained  in  the  DTDs 
presented  in  Appendix  A. 

Appendix  C  is  a  stand-alone  document  It  includes  a  document  output  specification 
(format  and  style  guide)  to  be  used  for  all  applications  of  this  specification.  Although  the 
format  default  values  are  set  according  to  MIL-M-38784A,  the  values  may  be  tailored  to 
satisfy  other  format  requirements.  The  appendix  also  provides  an  example  of  an  SGML- 
coded  source  file  and  the  composed  sample  document  produced  from  the  marked  up  file. 
2.8  DOD.STD.2167A,  "DEFENSE  SYSTEM  SOFTWARE  DEVELOP¬ 
MENT,"  29  FEBRUARY  1988 

DoD-STD-2167A  provides  the  means  for  establishing,  evaluating,  and  maintaining 
quality  in  software  developed  for  weapon  systems  and  its  associated  documentation.  The 
contract  agency  is  responsible  for  tailoring  the  software  management  process  to  meet  the 
needs  of  a  particular  project.  The  Data  Item  Descriptions  (DIDs)  associated  with  this 
standard  describe  a  set  of  documents  for  recording  information  required  by  the  management 
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process.  The  standard  encourages  the  production  of  deliverable  data  using  automated 
techniques. 
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3.0  ANALYSIS  OF  STANDARDS 

NnL-M-38784B  provides  very  strict  rules  for  the  preparation  of  technical  manuals. 
Technical  manuals  are  rigorously  defined,  emphasizing  hardware  and  hardware 
components  found  in  weapon  systems.  This  specification  docs  not  appear  to  address  the 
installation,  operation,  maintenance,  training  and  support  of  software.^  Over  the  past  years 
it  has  become  obvious  that  hardware  and  software  can  not  be  managed  in  the  same  way  and 
this  includes  the  documentation  associated  with  each. 

ISO-8879  provides  both  a  formal  specification  of  the  markup  language  and  a  set  of 
annexes  that  discuss  the  main  concepts  in  an  informal  tutorial  style.  Although  the  annexes 
are  helpful  in  understanding  the  standard,  it  is  also  true  that  the  standard  lacks  such 
important  items  as  an  index  and  a  list  of  abbreviations.  Recently,  Smith  and  Stutely  of  the 
UK  have  published  a  book  that  includes  SGML  syntax  productions,  a  list  of  abbreviations, 
character  entities  and  graphic  representations,  an  index  to  ISO  8879,  and  a  list  of  SGML 
keywords  and  reserved  names.  The  ISO  standard,  supplemented  by  this  text  and  the 
annexes,  should  provide  the  user  with  the  appropriate  information  to  utilize  SGML  to  its 
fullest  extent 

MIL-STD-1840A  is  not  concerned  with  the  specific  data  being  transferred,  but  the 
process  in  which  the  data  is  transferred.  A  very  detailed  declaration  file  with  15  separate 
records  must  be  included  in  the  transfer  of  data  from  one  source  to  another.  These  records 
state  everything  from  who  is  sending  the  document  to  when  the  last  change  was  made  to 
the  document  to  whether  or  not  graphic  files  are  included  in  the  document  The  data  files 
may  include  text  files,  illustration  files  and  product  data  files.  The  standard  is  concerned 
with  identifiers  or  records  rather  than  the  actual  text  or  graphics.  These  identifiers  appear  to 
be  very  good  reference  points,  especially  if  graphics  play  a  major  role  in  the  document 

MIL-D-28000  is  a  very  detailed  speciHcation  with  relationship  to  the  standards 
discussed,  28000  is  concerned  with  a  concrete  product  (i.e.,  hardware);  it  will  have  little  if 
any  impact  on  the  development  of  software  and  software-related  documentation.  As  stated 
earlier,  the  emphasis  is  on  component  and  circuit  element  descriptions,  their  placement, 
their  coimectivity,  and  the  routing  of  electrical  paths. 

Both  MIL-M-38784  and  MIL-STD-1840A  form  a  part  of  MIL-M-28001.  MIL-M- 
28001  translates  the  multiple  document  structures,  formats  and  style  of  specifications  such 


^Technical  content  is  provided  by  the  author — only  concern  of  the  standard  is  the  formatting  of  the 
information. 
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as  those  found  in  MIL-M-38784  into  rigorously  defined  terms  and  logical  constructs 
needed  for  electronic  interchange  and  publishing  purposes.  Two  DTDs  are  provided  in  this 
standard:  one  conforming  to  MIL-M-38784  and  one  non-conforming.  The  non¬ 
conforming  DTD  may  be  tailored  to  meet  the  needs  of  a  program.  There  is  also  a  document 
output  specification  associated  with  this  DTD  that  can  be  tailored  to  specific  needs  of  a 
program.  The  standard  allows  for  the  inclusion  of  illustrations  by  referencing  external 
graphics  files.  MIL-STD-1840A  provides  for  both  vector  and  raster  illustration  forms  of 
the  graphics  files  which  28001  utilizes.  The  authors  of  MIL-M-28001  feel  that  this 
speciAcation,  with  its  three  appendices,  supports  most  automated  publishing  applications 
within  the  DoD. 

Unlike  the  previous  standards  and  speciAcations,  DoD  standards  2167A  and  7935 
provide  guidelines  for  documentation  speciAc  to  software.  Although  both  standards  refer 
to  the  electronic  transfer  of  software  documentation,  no  speciAc  reference  is  made  to 
SGML  or  the  transfer  of  any  graphics  associated  with  the  documentation.  DoD-STD- 
2167A  does  provide  for  the  tailoring  of  the  standard  to  meet  the  needs  of  a  speciAc  program 
and  contracts. 
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4 . 0  RECOMMENDATIONS 

A  fundamental  end  product  of  the  STARS  Program  is  the  development  of  adaptable 
and  reliable  software  technology.  Tools,  environments,  and  repositories  will  be  built  to 
assist  in  the  acceptance  and  automation  of  this  technology.  STARS  has  mandated  that  all 
documentation  pertaining  to  this  technology  will  use  the  SGML  standard,  ISO  8879,  to 
define  its  structure  so  that  the  document  may  be  electronically  transferred  into  the  STARS 
software  repository.  The  review  of  the  seven  standards  and  the  subsequent 
recommendations  are  based  on  the  following  five  steps  which  should  be  taken  when  a 
program,  such  as  STARS,  plans  to  use  SGML  for  the  electronic  transfer  of  its  software 
documentation: 

1 .  Establish  Types  of  Required  Documentation 
Recommendation:  Review  DoD-STD-2167A  and  DoD-STD-7935  to  make 
sure  that  the  original  tailoring  effort  is  still  appropriate. 

With  the  superseding  of  DoD-STD-2167  by  DoD-STD-2167A,  STARS 
should  review  the  new  standard,  along  with  DoD-STD-7935,  to  make  sure 
the  original  tailoring  effort  is  still  appropriate  Both  of  these  standards 
provide  flexibility  so  that  the  standard  can  be  tailored  to  the  STARS 
software  development  process. 

There  are  various  types  of  documentation  that  can  accompany  software, 
i.e.,  User's  Manual,  Program  Maintenance  Manual,  and  Test  Plan.  STARS 
has  already  tailored  DoD-STD-2167  to  meet  its  needs.  The  types  of 
documentation  required  under  the  program  are  outlined  in  attachment "  A.6  - 
Delivery  Orders"  of  the  Software  Technology  for  Adaptable,  Reliable 
Systems  (STARS)  Competing  Primes  Lead  Contracts  and  the  "Contract 
Data  Requirements  Lists,"  which  specifies  those  deliverables  that  must  be 
submitted  electronically  in  SGML  format,  are  presented  in  attachment  A.7. 

2.  Establish  Document  Style  and  Structure  Guidelines 
Recommendation:  Generate  tailorings  of  DOD-STD-2167  A  and  DOD-STD- 
7935. 

Tailorings  of  DOD-STD-2167A  and  DOD-STD-7935  should  be  generated 
as  they  are  the  principle  standards  for  the  style  and  structure  of  software 
documentation.  MIL-M-38784B  addresses  primarily  weapon  system 
hardware  rather  than  software,  but  it  should  be  consulted  as  a  general 
guideline  for  technical  manuals. 


14 


3.  Establish  Document  Formatting  Guidelines 
Recommendation:  Use  MIL-M38784B  and  MIL-STD-1840A  as  guidelines 
for  formatting  documentation. 

Formatting  guidelines  are  provided  in  MIL-M-38784B  and  MIL-STD- 
1840A.  MIL-M-38784B  addresses  primarily  weapon  system  hardware 
rather  than  software,  but  it  should  be  consulted  as  a  general  guideline  for 
technical  manuals. 

4.  Establish  a  Standard  for  Graphical  Data 

Recommendation:  Use  MEL-STD-  1840A  and  MIL-D-28000  as  guidelines 
for  graphics  standard. 

Both  MIL-STD-1840A  and  MIL-D-28000  should  be  used  as  guidelines 
when  determining  the  graphics  standard  for  STARS  since  they  address 
different  types  of  graphical  data.  SGML  provides  for  the  inclusion  of 
graphical  data  such  as  figures  and  diagrams  in  documents,  but  does  not 
specify  the  representation  or  format  for  this  data.  The  term  graphics 
includes  illustrations,  engineering  drawings,  and  computer  graphics. 

5.  Establish  Appropriate  Document  Type  Definitions 
Recommendation:  Use  ISO-8879-1986(E)  and  MIL-M-28001  as 
guidelines  when  developing  its  DTDs. 

STARS  should  use  as  guidelines  ISO-8879- 1986(E)  and  MIL-M-28001 
when  developing  its  DTDs.  MIL-M-28001  has  already  done  a  significant 
work  in  this  area.  It  is  not  recommended  that  the  STARS  program  adopt  the 
rigid  DTD  for  a  MIL-M-38784  conforming  manual  presented  in  MIL-M- 
28001.  However,  it  would  be  beneficial  to  the  program  to  review  the  DTD 
developed  for  the  non-conforming  document  (Appendix  A,  Section  60). 
The  program  may  be  able  to  use  the  DTD  as  a  model  for  the  development  of 
a  more  appropriate  DTD.  The  document  output  specification  presented  in 
Appendix  C  of  the  specification  could  also  be  tailored  to  meet  the  needs  of 
STARS. 

Recommendation:  The  proposed  STARS  Standards  Working  Group  should 
be  tasked  to  investigate  how  these  and  other  standards  map  together.  This 
mapping  would  show  both  relationships  and  conflicts  among 
documentation-oriented  standards  that  impact  the  use  of  SGML  for 
electronic  transfer  of  documents. 
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